DIR$ Function
 ----------------------------------------------------------------------------


 Action

 Returns a filename that matches the specified pattern.


 Syntax

  DIR$-( filespec$)-


 Remarks

 The argument  filespec$ is a string expression that specifies a filename or
 path.

 The path and filename can include a drive and DOS wildcard characters.

 BASIC generates the error message Illegal function call if you don't specify
  filespec$ when you first call  DIR$.

  DIR$ returns the first filename that matches  filespec$. To retrieve
 additional filenames that match the  filespec$ pattern, call  DIR$ again
 with no argument. When no filenames match,  DIR$ returns a null string.

 You do not have to retrieve all of the filenames that match a given
 filespec$ before calling  DIR$ again with a new  filespec$.

 Because filenames are retrieved in no particular order, you may want to
 store filenames in a dynamic array and sort the array.

  DIR$ is not case sensitive. "C" is the same as "c."


 See Also

  CURDIR$


 Example

 The following example demonstrates use of the  DIR$ function.

 DECLARE FUNCTION GetFileCount& (filespec$)
 filespec$ = "*.*"
 count = GetFileCount(filespec$)
 PRINT count; "files match the file specification."

 ' Function that returns number of files that match file specification.
 FUNCTION GetFileCount& (filespec$)
 DIM FileCount AS LONG
     IF LEN(DIR$(filespec$)) = 0 THEN     ' Ensure filespec$ is valid.
         FileCount& = 0
     ELSE
         FileCount = 1
         DO WHILE LEN(DIR$) > 0
             FileCount& = FileCount& + 1
         LOOP
     END IF
     GetFileCount = FileCount&
 END FUNCTION